package org.mmtk.plan.scale.balance;

import org.vmmagic.pragma.Uninterruptible;
import org.vmmagic.unboxed.ObjectReference;

/**
 * Used to abstract the process of balancing object graph
 * by introducing new references into individual objects.
 * 
 * The process can be implemented by different 
 * concrete algorithms
 *  
 * @author kathy
 *
 */
@Uninterruptible  
public interface BalancerInterface {
	
	/**
	 * Called before the balancing process over the heap
	 * Balancer can initialize or reset counters and structures
	 * 
	 */
	public void initBalance();
	
	/**
	 * Analyze individual object encountered during trace
	 * and include it in the heap balancing process.
	 * Called by the tracer just after the object was popped off
	 * the stack and scanned for references.
	 * 
	 * @param objectRef object reference to process
	 * @param level	level in trace stack or distance from root
	 * @param children number of children encountered in this object scan
	 */
	public void processObject(ObjectReference objectRef, long level, int children);
	
	/**
	 * Report the results of the balancing process.
	 * Writes to the log
	 */
	public void reportBalance();
}
